Tool Mentor: Detecting Run-Time Errors using Rational PurifyÖ
Purpose
This tool mentor provides an overview of how to use Purify to find run-time errors in Visual C/C++ programs. To learn more about Purify, read Getting Ahead with Rational Purify. For step-by-step information about using Purify, see the Purify online Help.
Related Rational Unified Process activity: section "Execute Unit Test" in Activity: Perform Unit Tests.
Overview
Purify detects run-time errors, including memory leaks, both in your own code and in the components your software uses, even when you don't have the source code. It reports memory errors such as array bounds errors, access through dangling pointers, uninitialized memory reads, memory allocation errors, and memory leaks, so that you can resolve them before they do any damage. Purify can also report how thoroughly you have tested your code for errors, if you have Rational PureCoverage on your system. To test a program using Purify:
To ensure that you have Purify'd your entire program, take one more step:
Tool Steps
The first step in Purify'ing your code is to instrument and run your program.
In Microsoft Developer Studio 97 or later, engage Purify. If you have PureCoverage on your system, set Purify to collect coverage data. Then run the program that you want to Purify. Or, if you are not using Purify integrated with Developer Studio, just run the program in Purify. Purify instruments your code in preparation for detecting errors and collecting coverage data.
Purify provides a default level of instrumentation for each component, but you can use the PowerCheck tab in the settings dialogs to set the level of instrumentation you want. You can also set options to control how Purify handles error data. For example, you can specify whether Purify records and displays Uninitialized Memory Copy (UMC) messages, and you can specify the length of call stacks recorded for errors and allocations.
During instrumentation, Purify makes copies of the executable and its associated modules and uses Object Code Insertion (OCI) technology to insert into the code the instructions it uses to detect errors and monitor coverage. Purify shows you its progress as it instruments the executable file and modules.
After instrumentation, Purify starts the instrumented program. As you exercise the program, Purify displays a Data Browser window with an Error View tab that contains detailed diagnostics about the run-time errors it detects.
When you exit the program, Purify reports memory leaks. You can specify additional settings to have Purify also report memory and handles in use at exit.
Tip: In addition to using Purify interactively, you can also incorporate Purify into your test scripts, makefiles, and batch files for automated testing. For more information, look up scripts in the Purify online Help index.
More information? Look up instrumenting, running programs, and powercheck in the Purify online Help index.
The second step in Purify'ing your code is to analyze the Purify error data.
By default, the error view initially displays only the first line of each message. This condensed outline format makes it easy to scan the messages, quickly identify critical errors, and assess the state of the program. You can expand the outline to see more detailed diagnostic information.
Using this error view information, you can identify, understand, and eliminate hard-to-find memory access errors and memory leaks. You can also examine the source code, if debug and relocation data was available when you instrumented the program. Because Purify detects access errors at the point where they occur, and displays this information in the error view, you can easily track and eliminate these errors.
Because a large program can generate hundreds of error messages, Purify provides filters to hide messages and help you focus quickly on the most critical errors.
Tip: If you have incorporated Purify into your test scripts, makefiles, and batch files, you can automatically save error messages to an ASCII text file. For more information, look up scripts in the Purify online Help index.
More information? Look up error messages, error view, and filters in the Purify online Help index.
The third step in Purify'ing your code is to correct the errors and rerun the program.
To correct errors, double-click the line where the error occurs. Purify opens your source code in your editor at the exact location of the error, ready for correction.
After you correct and rebuild the program, you can verify your correction by rerunning the updated program and comparing the new results to the previous run. Repeat the cycle of instrumenting and running, analyzing, and correcting until your program runs clean.
You can use the Navigator window to switch between the two runs, and keep track of all the runs you're working with. You can also save error view data as a Purify data file, to share with colleagues who have Purify.
More information? Look up source code and saving data in the Purify online Help index.
If you collected coverage data for the program runs, you can also find the parts of your code that you have not Purify'd, and improve your testing coverage so that you find all the errors in your program, wherever they occur.
When you exit your program, Purify displays the coverage data in the Module View, File View, and Function List View tabs of the Data Browser window. These tabs show information such as the number of functions and lines hit and missed by your tests, as well as the percentage of functions and lines hit and missed. If debug line data is available and you monitored your code at line level, you can also use the Annotated Source window to analyze coverage for functions line by line.
Purify automatically filters out coverage data that is less interesting, such as data from system libraries, before displaying coverage data. You can create your own filters to hide additional data that you do not want to see, so that you can focus on what's important to your analysis.
By default, Purify automatically creates an Auto Merge entry on the Navigator window, so that you can easily analyze the total coverage of the program over multiple runs. You can also merge specific runs yourself, to see the cumulative effect of selected runs.
When you find weak spots in your coverage, rerun your program and test all the important parts, or revise your makefiles or test script to do a more thorough job. You can now have the confidence that errors are not lurking somewhere in the code that you failed to test, waiting to cause unexpected problems.
Tip: You can use /Coverage and related options to collect coverage data with Purify during automated testing. Look up command line, options in the Purify online Help index.
More information? Look up coverage data in the Purify online Help index.
